---
title: 가져오기
description: Astro로 다양한 콘텐츠 유형을 가져오는 방법을 알아보세요.
i18nReady: true
---

import RecipeLinks from '~/components/RecipeLinks.astro';
import ReadMore from '~/components/ReadMore.astro';

Astro는 구성이 필요하지 않은 대부분의 정적 자산을 지원합니다. 프로젝트 JavaScript (Astro 프런트매터 포함) 어디에서나 `import` 문을 사용할 수 있으며, Astro는 최종 빌드에 해당 정적 자산의 빌드되고 최적화된 복사본을 포함합니다. `@import`는 CSS 및 `<style>` 태그에서도 지원됩니다.

## 지원되는 파일 형식

Astro에서는 기본적으로 다음 파일 형식을 지원합니다.

- Astro 컴포넌트 (`.astro`)
- Markdown (`.md`, `.markdown` 등)
- JavaScript (`.js`, `.mjs`)
- TypeScript (`.ts`, `.tsx`)
- NPM 패키지
- JSON (`.json`)
- JSX (`.jsx`, `.tsx`)
- CSS (`.css`)
- CSS 모듈 (`.module.css`)
- 이미지 및 자산 (`.svg`, `.jpg`, `.png` 등)

또한 Astro를 확장하여 React, Svelte, Vue 컴포넌트와 같은 다양한 [UI 프레임워크](/ko/guides/framework-components/)에 대한 지원을 추가할 수 있습니다. [Astro MDX 통합](/ko/guides/integrations-guide/mdx/)을 설치하고 프로젝트에서 `.mdx` 파일을 사용할 수도 있습니다.

### `public/` 디렉터리 내 파일

프로젝트의 [`public/` 디렉터리](/ko/basics/project-structure/#public)에 정적 자산을 배치할 수 있으며 Astro는 이를 그대로 최종 빌드에 직접 복사합니다. `public/` 파일은 Astro에서 빌드되거나 번들로 제공되지 않습니다. 즉, 모든 유형의 파일이 지원된다는 의미입니다. HTML 템플릿에서 직접 URL 경로로 `public/` 파일을 참조할 수 있습니다.

## Import 구문

Astro는 브라우저에서 지원되는 것과 동일한 [`import`](https://developer.mozilla.org/ko/docs/Web/JavaScript/Reference/Statements/import) 및 [`export`](https://developer.mozilla.org/ko/docs/Web/JavaScript/Reference/Statements/export) 구문인 ESM을 사용합니다.

### JavaScript

```js
import { getUser } from './user.js';
```

JavaScript는 일반적인 ESM `import` & `export` 구문을 사용하여 가져올 수 있습니다.

### TypeScript

```js
import { getUser } from './user';
import type { UserType } from './user';
```

Astro에는 [TypeScript](https://www.typescriptlang.org/ko/)에 대한 지원이 내장되어 있습니다. Astro 프로젝트에서 직접 `.ts` 및 `.tsx` 파일을 가져올 수 있으며. [Astro 컴포넌트 스크립트](/ko/basics/astro-components/#컴포넌트-스크립트) 및 [호이스팅된 스크립트 태그](/ko/guides/client-side-scripts/)에 TypeScript 코드를 직접 작성할 수도 있습니다.

**Astro는 자체적으로 어떠한 타입 검사도 수행하지 않습니다.** 타입 검사는 Astro 외부에서 IDE나 별도의 스크립트를 통해 처리해야 합니다. Astro 파일의 타입 검사를 위해 [`astro check` 명령](/ko/reference/cli-reference/#astro-check)이 제공됩니다.

:::note[TypeScript 및 파일 확장자]
[TypeScript의 모듈 확인 규칙](https://www.typescriptlang.org/docs/handbook/module-resolution.html)에 따라 TypeScript 파일을 가져올 때 `.ts` 및 `.tsx` 파일 확장자를 사용하면 안 됩니다. 대신 `.js`/`.jsx` 파일 확장자를 사용하거나 파일 확장자를 완전히 생략하세요.

```ts
import { getUser } from './user.js'; // user.ts
import MyComponent from './MyComponent'; // MyComponent.tsx
```
:::

<ReadMore>[Astro의 TypeScript 지원](/ko/guides/typescript/)에 대해 자세히 알아보세요.</ReadMore>

### JSX / TSX

```js
import { MyComponent } from './MyComponent.jsx';
```

Astro에는 JSX (`*.jsx` 및 `*.tsx`) 파일에 대한 지원이 내장되어 있습니다. JSX 구문은 자동으로 JavaScript로 변환됩니다.

Astro는 기본적으로 JSX 구문을 이해하지만 React, Preact, Solid와 같은 프레임워크를 적절하게 렌더링하려면 프레임워크 통합을 포함해야 합니다. 자세한 내용은 [통합 사용](/ko/guides/integrations-guide/) 안내서를 확인하세요.

:::note
**Astro는 `.js`/`.ts` 파일에서 JSX를 지원하지 않습니다.** JSX는 `.jsx` 및 `.tsx` 파일 확장자로 끝나는 파일에서만 처리됩니다.
:::

### NPM 패키지

NPM 패키지를 설치한 경우 Astro로 가져올 수 있습니다.

```astro
---
import { Icon } from 'astro-icon';
---
```

패키지가 레거시 형식을 사용하여 게시된 경우 Astro는 `import` 문이 작동하도록 패키지를 ESM으로 변환하려고 시도합니다. 어떤 경우에는 [`vite` 구성](/ko/reference/configuration-reference/#vite)을 조정해야 작동할 수도 있습니다.

:::caution
일부 패키지는 브라우저 환경에 의존합니다. Astro 컴포넌트는 서버에서 실행되므로 프런트매터에서 이러한 패키지를 가져오면 [오류가 발생할 수 있습니다](/ko/guides/troubleshooting/#document-or-window-is-not-defined).
:::

### JSON

```js
// 기본 내보내기를 통해 JSON 객체 불러오기
import json from './data.json';
```

Astro는 JSON 파일을 애플리케이션으로 직접 가져오는 것을 지원합니다. 가져온 파일은 기본 가져오기에서 전체 JSON 객체를 반환합니다.

### CSS

```js
// 페이지에 'style.css' 불러오기 및 삽입
import './style.css';
```

Astro는 CSS 파일을 애플리케이션으로 직접 가져오는 것을 지원합니다. 가져온 스타일은 내보내기를 노출하지 않지만 스타일을 가져오면 해당 스타일이 페이지에 자동으로 추가됩니다. 이는 기본적으로 모든 CSS 파일에 대해 작동하며 플러그인을 통해 Sass & Less와 같은 CSS로 컴파일 언어를 지원할 수 있습니다.

### CSS 모듈

```jsx
// 1. './style.module.css' 클래스 이름을 고유한 범위 값으로 변환합니다.
// 2. 원래 클래스 이름을 최종 범위 값에 매핑하는 객체를 반환합니다.
import styles from './style.module.css';

// 이 예시에서는 JSX를 사용하지만 모든 프레임워크에서 CSS 모듈을 사용할 수 있습니다.
return <div className={styles.error}>에러 메시지</div>;
```

Astro는 `[name].module.css` 명명 규칙을 사용하여 CSS 모듈을 지원합니다. 다른 CSS 파일과 마찬가지로 파일을 가져오면 해당 CSS가 페이지에 자동으로 적용됩니다. 그러나 CSS 모듈은 원래 클래스 이름을 고유 식별자에 매핑하는 특별한 기본 `styles` 객체를 내보냅니다.

CSS 모듈은 스타일시트에 대해 고유하게 생성된 클래스 이름을 사용하여 프런트엔드에서 컴포넌트 범위 지정 및 격리를 적용하는 데 도움이 됩니다.

### 기타 자산

```jsx
import imgReference from './image.png'; // imgReference === '/src/image.png'
import svgReference from './image.svg'; // svgReference === '/src/image.svg'
import txtReference from './words.txt'; // txtReference === '/src/words.txt'

// 이 예시에서는 JSX를 사용하지만 모든 프레임워크에서 가져오기 참조를 사용할 수 있습니다.
<img src={imgReference.src} alt="이미지 설명" />;
```

위에 명시적으로 언급되지 않은 다른 모든 자산은 ESM `import`를 통해 가져올 수 있으며 최종 빌드된 자산에 대한 URL 참조를 반환합니다. 이는 해당 이미지를 가리키는 `src` 속성을 사용하여 이미지 요소를 생성하는 것과 같이 JS가 아닌 자산을 URL로 참조하는 데 유용할 수 있습니다.

[프로젝트 구조 페이지](/ko/basics/project-structure/#public)에 설명된 대로 `public/` 폴더에 이미지를 배치하는 것도 유용할 수 있습니다.

:::note
접근성을 위해 `<img>` 태그에 **대체 텍스트**를 추가하는 것이 좋습니다! 이미지 요소에 `alt="유용한 설명"` 속성을 추가하는 것을 잊지 마세요. 이미지가 순전히 장식용인 경우 속성을 비워 둘 수 있습니다.
:::

## `Astro.glob()`

[`Astro.glob()`](/ko/reference/api-reference/#astroglob)은 한 번에 많은 파일을 가져오는 방법입니다.

`Astro.glob()`은 하나의 매개변수, 즉 가져오려는 로컬 파일과 일치하는 상대 [glob 패턴](#glob-패턴)만 사용합니다. 비동기식이며 각 파일의 내보내기와 일치하는 배열을 반환합니다.

```astro title="src/components/my-component.astro"
---
// `./src/pages/post/`에서 `.md`로 끝나는 모든 파일을 가져옵니다.
const posts = await Astro.glob('../pages/post/*.md');
---

<!-- 처음 5개의 블로그 게시물에 대한 <article>을 렌더링합니다. -->
<div>
  {
    posts.slice(0, 4).map((post) => (
      <article>
        <h2>{post.frontmatter.title}</h2>
        <p>{post.frontmatter.description}</p>
        <a href={post.url}>계속 읽기</a>
      </article>
    ))
  }
</div>
```

`Astro.glob`을 사용하여 가져온 Astro 컴포넌트는 [`AstroInstance`](/ko/reference/api-reference/#astro-파일) 타입입니다. `default` 속성을 사용하여 각 컴포넌트 인스턴스를 렌더링할 수 있습니다.

```astro title="src/pages/component-library.astro" {8}
---
// `./src/components/`에서 `.astro`로 끝나는 모든 파일을 가져옵니다.
const components = await Astro.glob('../components/*.astro');
---

<!-- 모든 컴포넌트 표시 -->{
  components.map((component) => (
    <div>
      <component.default size={24} />
    </div>
  ))
}
```

### Glob 패턴

glob 패턴은 특수 와일드카드 문자를 지원하는 파일 경로입니다. 이는 프로젝트의 여러 파일을 한 번에 참조하는 데 사용됩니다.

예를 들어 glob 패턴 `./pages/**/*.{md,mdx}`는 페이지 하위 디렉터리에서 시작하여 모든 하위 디렉터리 (`/**`)를 검색하고 `.md` 또는 `.mdx` (`.{md,mdx}`)로 끝나는 모든 파일 이름 (`/*`)을 찾습니다.

#### Astro의 Glob 패턴

`Astro.glob()`과 함께 사용하려면 glob 패턴이 문자열 리터럴이어야 하며 어떤 변수도 포함할 수 없습니다. 해결 방법은 [문제 해결 가이드](/ko/guides/troubleshooting/#astroglob---일치하는-항목이-없습니다)를 참조하세요.

또한 glob 패턴은 다음 중 하나로 시작해야 합니다.

- `./` (현재 디렉터리에서 시작)
- `../` (상위 디렉터리에서 시작)
- `/` (프로젝트 루트에서 시작)

[glob 패턴 구문에 대해 자세히 알아보세요](https://github.com/mrmlnc/fast-glob#pattern-syntax).

#### `Astro.glob()` vs `getCollection()`

[콘텐츠 컬렉션](/ko/guides/content-collections/)은 `Astro.glob()` 대신 여러 파일을 가져오기 위한 [`getCollection()` API](/ko/reference/api-reference/#getcollection)를 제공합니다. 콘텐츠 파일 (예: Markdown, MDX, Markdoc)이 `src/content/` 디렉터리의 컬렉션에 있는 경우 `getCollection()`을 사용하여 [컬렉션을 쿼리](/ko/guides/content-collections/#컬렉션-쿼리)하고 콘텐츠 항목을 반환합니다.

## WASM

```js
// 요청된 WASM 파일을 가져와 초기화합니다.
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));
```

Astro는 브라우저의 [`WebAssembly`](https://developer.mozilla.org/ko/docs/WebAssembly/JavaScript_interface) API를 사용하여 WASM 파일을 애플리케이션에 직접 로드하는 것을 지원합니다.

## Node 내장

Astro 사용자는 가능하면 Node.js 내장 기능(`fs`, `path` 등)을 피하는 것이 좋습니다. Astro는 [어댑터](/ko/guides/server-side-rendering/)를 사용하여 여러 런타임과 호환됩니다. 여기에는 `fs`와 같은 노드 내장 모듈을 지원하지 않는 [Deno](https://github.com/denoland/deno-astro-adapter) 및 [Cloudflare Workers](/ko/guides/integrations-guide/cloudflare/)가 포함됩니다.

우리의 목표는 일반적인 Node.js 내장 기능에 대한 Astro 대안을 제공하는 것입니다. 그러나 오늘날에는 그러한 대안이 존재하지 않습니다. 따라서 이러한 내장 모듈을 _반드시_ 사용해야 하는 경우에도 우리는 여러분을 막고 싶지 않습니다. Astro는 Node의 최신 `node:` 접두사를 사용하여 Node.js 내장 기능을 지원합니다. 예를 들어 파일을 읽으려면 다음과 같이 할 수 있습니다.

```astro title="src/components/MyComponent.astro"
---
// 예: Node.js에서 내장된 "fs/promises" 가져오기
import fs from 'node:fs/promises';

const url = new URL('../../package.json', import.meta.url);
const json = await fs.readFile(url, 'utf-8');
const data = JSON.parse(json);
---

<span>버전: {data.version}</span>
```

## 파일 형식 지원 확장

**Vite** 및 호환되는 **Rollup** 플러그인을 사용하면 Astro에서 기본적으로 지원하지 않는 파일 형식을 가져올 수 있습니다. Vite 문서의 [플러그인 찾기](https://ko.vitejs.dev/guide/using-plugins.html#finding-plugins) 섹션에서 필요한 플러그인을 찾아보세요.

:::note[플러그인 구성]
구성 옵션과 올바르게 설치하는 방법은 플러그인 설명서를 참조하세요.
:::

<RecipeLinks slugs={['ko/recipes/add-yaml-support']} />
